Inside Macintosh: QuickDraw GX Objects /

Chapter 7 - View-Related Objects / View-Related Objects Reference

View Device Functions / Retrieving the View Devices That Intersect a Shape

GXGetShapeGlobalViewDevices

You can use the GXGetShapeGlobalViewDevices function to determine which view devices intersect the area of a shape.

long GXGetShapeGlobalViewDevices(gxShape source, gxViewPort port,
                                 gxViewDevice list[]);

source

A reference to the shape whose view devices you wish to retrieve.

port

A reference to a view port that the shape is drawn to.

list

An array of view device references. On return, the array lists the view devices that the shape is drawn on.

function result

The number of view devices that the shape is drawn on.

DESCRIPTION

The GXGetShapeGlobalViewDevices function retrieves a list of view devices that the source shape is drawn on, through the specified view port. The view port must be in the view port list of the shape's transform object. A returned view device object must have a clip that intersects the clip of the specified view port, and the shape drawn to the view port must also intersect the view device clip.

If the port parameter is set to nil, all view ports in the view port list of the shape's transform object are used.

If you set the list parameter to nil, GXGetShapeGlobalViewDevices does not fill out the list of references; it only returns the number of view device references that would be in the list (which may be 0). Thus, you typically call this function twice: first to get the size of array to allocate for the list parameter, and second to retrieve the list itself.

As one application of this function, you could call GXGetShapeGlobalViewPorts to determine the view ports to which a shape is drawn. You then could use one of these view ports in a call to GXGetShapeGlobalViewDevices to determine the view devices that the shape would be drawn to.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
invalid_viewPort_reference

SEE ALSO

For examples of the use of this function, see Listing 7-12 on page 7-58 and Listing 7-13 on page 7-61.

The GXGetShapeGlobalViewPorts function is described on page 7-95.